feat(query): narrow joined columns proven not NULL by where - #103

A LEFT JOIN types its columns as T | null. A where that proves a column present (isNotNull(), eq(…)) did not change that, so app code added ! or extra checks after the query.

Closes #67.
Part of #52.

Changes

• Left-join nullability was already there (NullableColumnDefs, NullOr codecs). This PR adds the narrowing on top of it.
• Condition gets a second type parameter, F, for not-NULL facts. It defaults to {}, so existing code does not change. A condition can drop a fact on assignment but cannot gain one.
• On a joined column, isNotNull() and eq(…) return a condition with a fact (NULL = x is never true). FROM columns give no fact.
• .and(…), and(…), the items of a where list and a second where keep the facts. or, .or, not, when, whenTrue, an item typed | undefined and a list of unknown length give none.
• where returns NarrowJoins<Joins, Facts>: a proven column loses | null, and a Nullable column loses its own NULL too. With no facts, Joins stays the same type.
• Runtime: select records the where conditions that exist when it is called (selectWhereFn). compile reads their facts (src/ch/facts.ts, a WeakMap like the tenant evidence) and gives the proven joined columns their non-null codec. So the row type and the derived row schema agree, and a NULL in a narrowed column fails to decode. This also works for leftJoinQuery and for a fromQuery over a narrowed query.
• ColumnRef gets a phantom _columnType. Without it, the new Source parameter made the compiler compare refs member by member, and strRef.get("k") on a non-Map column stopped being a type error.
• Tests: src/ch/predicate-facts.test-d.ts (types), src/ch/predicate-facts.test.ts (row schema, ClickHouse and Postgres), a live case left-join-not-null in tests/core-cases.ts, and a declaration-emit export in tests/package-consumer-declarations.mts.
• Docs: docs/joins-and-subqueries.md (new section, backed by a docs example test), docs/reference.md. Changeset: minor.

Left out

• Order: only a select after the where is narrowed. A select made before it keeps | null, because its row type is fixed when you call it. Narrowing an earlier select needs the output to remember which column each field came from. That is a larger change.
• FROM-table columns declared Nullable: no narrowing yet. This keeps the Cols type unchanged in this PR. The same mechanism can cover them later.
• in_(…) narrowing, and narrowing a literal union by eq / in_ (the issue's third "done when" item). This PR only removes null.
• OR / NOT reasoning (for example not(isNull()), or the same fact on both sides of an or). These prove nothing in this PR, which is sound but less precise.
• The runtime schema can be stricter than the type in one case: a fact inside an item typed | undefined, or inside a list of unknown length, that renders at run time. The type keeps | null there, and the decoder refuses a NULL that SQL cannot return anyway.
• ClickHouse without join_use_nulls=1 fills a missing join row with the column default, not NULL. isNotNull() keeps that row. The narrowed type is still correct, because the value is not NULL. The live case shows both settings.
• Nothing needs SQLite, MySQL or D1.

Validation

• bun run build: pass.
• bun run typecheck: pass (src and tests).
• bunx vitest run --testTimeout=60000 --hookTimeout=60000 with a live ClickHouse 26.8.2.7 (EFFECT_ORM_CLICKHOUSE_URL / _USER / _PASSWORD set): 61 files passed, 1047 tests passed, 0 skipped files.
• node scripts/check-doc-citations.mjs, node scripts/check-doc-examples.mjs, node scripts/check-exports-documented.mjs: pass.
• bun scripts/check-package.ts: pass (declaration emit includes a narrowed query).
• Upstream CI for a fork PR waits for a maintainer to approve the run.

^{Need help on this PR? Tag @codesmith-bot with what you need.}